.\" $OpenBSD: iogen.8,v 1.8 2007/05/18 14:48:16 marco Exp $
.\"
.\" Copyright (c) 2005 Marco Peereboom <marco@peereboom.us>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd December 6, 2005
.Dt IOGEN 8
.Os
.Sh NAME
.Nm iogen
.Nd I/O generator
.Sh SYNOPSIS
.Nm iogen
.Bk -words
.Op Fl kr
.Op Fl b Ar max-io-size
.Op Fl d Ar target-directory
.Op Fl f Ar result-directory
.Op Fl n Ar nr-forks
.Op Fl p Ar read-percentage
.Op Fl s Ar max-file-size
.Op Fl t Ar update-time
.Ek
.Sh DESCRIPTION
.Nm
is a lightweight tool that generates heavily fragmented I/O.
It accomplishes this by forking a number of children that run I/O to a
filesystem.
.Pp
This tool is intended to test storage stacks under stress and worst case
scenarios.
However due to heavy fragmentation of the I/O files,
it tends to bypass caching algorithms in storage stacks.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl b Ar max-io-size
This is the fixed I/O size unless the -r flag is set.
The default is 64KB.
.It Fl d Ar target-directory
This is the directory where the I/O file will be written to.
The default is the current working directory.
.It Fl f Ar result-directory
This is the directory where the result file will be written to.
The result file is updated every
.Ar update-time
seconds with statistics.
The default is the current working directory.
.It Fl k
Kill all running
.Nm
processes.
.It Fl n Ar nr-forks
This will determine how many identical processes will be forked to run I/O.
The default is 1.
.It Fl p Ar read-percentage
This determins the read vs write distribution.
The range is from 10% to 90%.
The default is 50.
.It Fl P Ar pattern
Pattern is a whole number that designates the IO pattern.  The default is a
text pattern that is human readable.  Use ? to print out the available
patterns.
.It Fl r
Randomize I/O size between 1 and
.Ar max-io-size .
Enabling this flag will disable data verification.
The default is disabled.
.It Fl s Ar max-file-size
The file where the I/O is run to and from will grow sequentially until it is
bigger or equal to this value.
At that point all write I/O will also become random.
The default is 1GB.
.It Fl t Ar update-time
This determines the minimal amount of time between updates.
Under heavy I/O this value can be skewed due to
the asynchronous nature of
.Xr alarm 3 .
The default is 60 seconds.
.It Fl T Ar I/O timeout
This determines the maximum time an I/O run is allowed to take to complete.
If the timeout is reached all iogen processes will be terminated.
The default is disabled.
.El
.Pp
Although the algorithm for I/O generation is incredibly simple,
it has proven to be very effective at
bringing out issues in storage stacks.
It first grows the initial file a minimal amount to be able to start running
I/O in it.
After the initial growth,
it reads randomly within the current file size.
Every run is a distribution between reads and writes which is governed by
the read percentage value.
The file is grown sequentially until it reaches maximum file size.
Whenever this happens a message is logged to syslogd(8) and all writes become
random.
.Pp
To monitor progress one can
.Xr tail 1
the result file which is updated every
.Ar update-time
interval or send the process a
.Dv HUP
signal.
Whenever an I/O process receives a
.Dv HUP
signal, it prints statistical values to
.Xr stderr 4
at its earliest convenience.
.Pp
Whenever iogen runs into data corruption or a failed read or write it will
terminate all child processes.
.Sh EXAMPLES
Run iogen with all defaults in the current working directory:
.Pp
.Dl $ iogen
.Pp
Run
.Nm
with all defaults and a 1 second result file update:
.Pp
.Dl $ iogen -t 1
.Pp
Run
.Nm
with a 2GB max file, 128KB I/O size, and result file in
.Pa /tmp :
.Pp
.Bd -literal -offset indent
$ iogen -s 2g -b 128k -t 1 -f /tmp
.Ed
.Sh HISTORY
The first version of
.Nm
was written in 2005.
.Sh AUTHORS
.An Marco Peereboom Aq marco@peereboom.us
.Sh CAVEATS
This tool is capable of running extremely heavy I/O.
It is known to have broken hardware before so please use caution and don't
complain if something bad happens.
